Doc fixes

https://bugzilla.gnome.org/show_bug.cgi?id=663277

diff --git a/docs/reference/shell/Makefile.am b/docs/reference/shell/Makefile.am
index b8c68d1740b65f640d3f3a8351d20c53d9cd3375..61cde1f6ff1a2ea97cdeb32af606bee4d2fd30fd 100644 (file)
--- a/docs/reference/shell/Makefile.am
+++ b/docs/reference/shell/Makefile.am
@@ -58,7 +58,7 @@ EXTRA_HFILES=
 
 # Header files or dirs to ignore when scanning. Use base file/dir names
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
-IGNORE_HFILES=calendar-server gvs hotplug-sniffer st tray
+IGNORE_HFILES=calendar-server gvc hotplug-sniffer st tray
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png

diff --git a/src/main.c b/src/main.c
index aceb298dbdcb18be97795a637c107542a915ea3c..f759d23a8ecca4737e2a571425d2de778be66b8a 100644 (file)
--- a/src/main.c
+++ b/src/main.c
@@ -96,7 +96,7 @@ shell_dbus_init (gboolean replace)
   guint32 request_name_flags;
   guint32 request_name_result;
 
-  /** TODO:
+  /* TODO:
    * In the future we should use GDBus for this.  However, in
    * order to do that, we need to port all of the JavaScript
    * code.  Otherwise, the name will be claimed on the wrong

diff --git a/src/shell-app.c b/src/shell-app.c
index 53d75ee157da92cbabecc669abc58e3c561b8eb5..3d1e78afacb35de10de6f0713789b759214ca4d9 100644 (file)
--- a/src/shell-app.c
+++ b/src/shell-app.c
@@ -1220,12 +1220,13 @@ shell_app_init_search_data (ShellApp *app)
 
 /**
  * shell_app_compare_by_name:
- * @app:
- * @other:
+ * @app: One app
+ * @other: The other app
  *
  * Order two applications by name.
  *
- * Returns: -1, 0, or 1; suitable for use as a comparison function for e.g. g_slist_sort()
+ * Returns: -1, 0, or 1; suitable for use as a comparison function
+ * for e.g. g_slist_sort()
  */
 int
 shell_app_compare_by_name (ShellApp *app, ShellApp *other)

diff --git a/src/shell-doc-system.c b/src/shell-doc-system.c
index 78b1637dd22008a8963c3e89065c91190029cded..6572c56a9dbdd4d5de1daf34bf1eb3cf492ebafd 100644 (file)
--- a/src/shell-doc-system.c
+++ b/src/shell-doc-system.c
@@ -52,16 +52,17 @@ shell_doc_system_get_all (ShellDocSystem    *self)
 }
 
 /**
- * @self: A #ShellDocSystem
- * @uri: Url
+ * shell_doc_system_lookup_by_uri:
+ * @system: A #ShellDocSystem
+ * @uri: URI
  *
  * Returns: (transfer none): Recent file info corresponding to given @uri
  */
 GtkRecentInfo *
-shell_doc_system_lookup_by_uri (ShellDocSystem  *self,
+shell_doc_system_lookup_by_uri (ShellDocSystem  *system,
                                 const char      *uri)
 {
-  return g_hash_table_lookup (self->priv->infos_by_uri, uri);
+  return g_hash_table_lookup (system->priv->infos_by_uri, uri);
 }
 
 static gboolean

diff --git a/src/shell-global.c b/src/shell-global.c
index 0c7961a4398c89c460d6050ca2fba85245559a85..b5f2eddec389c8b0b4a05edcd8755c8740c14ce1 100644 (file)
--- a/src/shell-global.c
+++ b/src/shell-global.c
@@ -857,7 +857,7 @@ _shell_global_get_gjs_context (ShellGlobal *global)
  * overview mode or the "looking glass" debug overlay, that block
  * application and normal key shortcuts.
  *
- * Returns value: %TRUE if we succesfully entered the mode. %FALSE if we couldn't
+ * Returns: %TRUE if we succesfully entered the mode. %FALSE if we couldn't
  *  enter the mode. Failure may occur because an application has the pointer
  *  or keyboard grabbed, because Mutter is in a mode itself like moving a
  *  window or alt-Tab window selection, or because shell_global_begin_modal()
@@ -1964,7 +1964,7 @@ shell_global_screenshot_window (ShellGlobal  *global,
  * will enable a login dialog and run in a more confined
  * way. This type is suitable for the display manager.
  *
- * Returns the type of session gnome-shell is providing.
+ * Returns: the type of session gnome-shell is providing.
  */
 ShellSessionType
 shell_global_get_session_type (ShellGlobal  *global)

diff --git a/src/shell-mobile-providers.c b/src/shell-mobile-providers.c
index 5d985ed09efe1a0e7b6fe046ee9670844511cf20..13a8b3ece81e61f915f46e595edb600aa3fb448e 100644 (file)
--- a/src/shell-mobile-providers.c
+++ b/src/shell-mobile-providers.c
@@ -619,9 +619,9 @@ static const GMarkupParser mobile_parser = {
  * @out_ccs: (out) (allow-none): (element-type utf8 utf8): a #GHashTable containing
  *   country codes
  *
- * Returns: (element-type utf8 GList<Shell.MobileProvider>) (transfer container): a
- *   hash table where keys are country names 'char *', values are a 'GSList *'
- *   of 'ShellMobileProvider *'. Everything is destroyed with g_hash_table_destroy ().
+ * Returns: (element-type utf8 GList) (transfer container): a
+ *   hash table where keys are country names #gchar, values are a #GSList
+ *   of #ShellMobileProvider. Everything is destroyed with g_hash_table_destroy().
 */
 GHashTable *
 shell_mobile_providers_parse (GHashTable **out_ccs)

diff --git a/src/shell-perf-log.c b/src/shell-perf-log.c
index 7132b874ca71480bbc6ba0d43697409de6162fef..72c4210e2ffd68e3636479f1908dadcac8f21ada 100644 (file)
--- a/src/shell-perf-log.c
+++ b/src/shell-perf-log.c
@@ -590,7 +590,7 @@ shell_perf_log_update_statistic_x (ShellPerfLog *perf_log,
 }
 
 /**
- * shell_perf_log_add statistics_callback:
+ * shell_perf_log_add_statistics_callback:
  * @perf_log: a #ShellPerfLog
  * @callback: function to call before recording statistics
  * @user_data: data to pass to @callback

diff --git a/src/shell-recorder-src.c b/src/shell-recorder-src.c
index 3c6bdefcfebc80c7894f901289e24055f140c25d..59a517e15c45871c04c08252516a7074442fecaf 100644 (file)
--- a/src/shell-recorder-src.c
+++ b/src/shell-recorder-src.c
@@ -282,6 +282,7 @@ plugin_init (GstPlugin *plugin)
 
 /**
  * shell_recorder_src_register:
+ *
  * Registers a plugin holding our single element to use privately in
  * this application. Can safely be called multiple times.
  */

diff --git a/src/shell-recorder.h b/src/shell-recorder.h
index fe96c5b5b271fbc90be4ef5f2015733f140bb331..5f00e6ee125da7cd75f3c40b7393fc8fc645fd85 100644 (file)
--- a/src/shell-recorder.h
+++ b/src/shell-recorder.h
@@ -7,8 +7,8 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:ShellRecorder
- * short_description: Record from a #ClutterStage
+ * SECTION:shell-recorder
+ * @short_description: Record from a #ClutterStage
  *
  * The #ShellRecorder object is used to make recordings ("screencasts")
  * of a #ClutterStage. Recording is done via #GStreamer. The default is

diff --git a/src/shell-window-tracker.c b/src/shell-window-tracker.c
index b0251d27071277a83645597f47f4fc4e69d88394..adb7fb788dce364a68d9c165b2bd53dd9511d12d 100644 (file)
--- a/src/shell-window-tracker.c
+++ b/src/shell-window-tracker.c
@@ -639,7 +639,7 @@ shell_window_tracker_get_window_app (ShellWindowTracker *tracker,
 
 /**
  * shell_window_tracker_get_app_from_pid:
- * @self; A #ShellAppSystem
+ * @tracker: A #ShellAppSystem
  * @pid: A Unix process identifier
  *
  * Look up the application corresponding to a process.
@@ -647,7 +647,7 @@ shell_window_tracker_get_window_app (ShellWindowTracker *tracker,
  * Returns: (transfer none): A #ShellApp, or %NULL if none
  */
 ShellApp *
-shell_window_tracker_get_app_from_pid (ShellWindowTracker *self, 
+shell_window_tracker_get_app_from_pid (ShellWindowTracker *tracker,
                                        int                 pid)
 {
   GSList *running = shell_app_system_get_running (shell_app_system_get_default());

diff --git a/src/shell-xfixes-cursor.c b/src/shell-xfixes-cursor.c
index 6507d19a8c5149b21b03d2f085e15b9b9ef0ceb9..fd8f2e156a8164ab30c7d3f3cd740a9331619120 100644 (file)
--- a/src/shell-xfixes-cursor.c
+++ b/src/shell-xfixes-cursor.c
@@ -8,8 +8,8 @@
 #include <X11/extensions/Xfixes.h>
 
 /**
- * SECTION:ShellXFixesCursor
- * short_description: Capture/manipulate system mouse cursor.
+ * SECTION:shell-xfixes-cursor
+ * @short_description: Capture/manipulate system mouse cursor.
  *
  * The #ShellXFixesCursor object uses the XFixes extension to show/hide the
  * the system mouse pointer, to grab its image as it changes, and emit a

diff --git a/src/st/st-group.c b/src/st/st-group.c
index 1395af211bc7fe64c811f6c325eddf94a4e176ef..fac012465d202fb9e82d3884bc4b253ba7efbb72 100644 (file)
--- a/src/st/st-group.c
+++ b/src/st/st-group.c
@@ -20,7 +20,7 @@
 
 /**
  * SECTION:st-group
- * SECTION:clutter-group
+ * @see_also:#ClutterGroup
  * @short_description: A fixed layout container
  *
  * A #StGroup is an Actor which contains multiple child actors positioned

diff --git a/src/st/st-im-text.c b/src/st/st-im-text.c
index 92574ff6797d23d25f792b4b3ef8e90107c2bef5..8c244403bbc471d978e495ffbd4a1ef87ff1fece 100644 (file)
--- a/src/st/st-im-text.c
+++ b/src/st/st-im-text.c
@@ -25,7 +25,7 @@
  */
 
 /**
- * SECTION:StIMText
+ * SECTION:st-im-text
  * @short_description: Text widget with input method support
  * @stability: Unstable
  * @see_also: #ClutterText

diff --git a/src/st/st-scroll-view.c b/src/st/st-scroll-view.c
index 63e66c1a6e3218bcedbd5fe3ecbea2bbc652e9a7..6f6beb2195731cf2f16750cabab61b2abf0fe8ed 100644 (file)
--- a/src/st/st-scroll-view.c
+++ b/src/st/st-scroll-view.c
@@ -963,7 +963,7 @@ st_scroll_view_new (void)
  *
  * Gets the horizontal scrollbar of the scrollbiew
  *
- * Return value: (transfer none): the horizontal #StScrollbar
+ * Return value: (transfer none): the horizontal #StScrollBar
  */
 ClutterActor *
 st_scroll_view_get_hscroll_bar (StScrollView *scroll)
@@ -979,7 +979,7 @@ st_scroll_view_get_hscroll_bar (StScrollView *scroll)
  *
  * Gets the vertical scrollbar of the scrollbiew
  *
- * Return value: (transfer none): the vertical #StScrollbar
+ * Return value: (transfer none): the vertical #StScrollBar
  */
 ClutterActor *
 st_scroll_view_get_vscroll_bar (StScrollView *scroll)

diff --git a/src/st/st-theme-context.h b/src/st/st-theme-context.h
index 6e6ee3cb2c48d0ebfae257a7801783a509ae0f7c..8805fb19b0b061b26692f1ebfac7158f91f55d9d 100644 (file)
--- a/src/st/st-theme-context.h
+++ b/src/st/st-theme-context.h
@@ -29,7 +29,7 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:StThemeContext
+ * SECTION:st-theme-context
  * @short_description: holds global information about a tree of styled objects
  *
  * #StThemeContext is responsible for managing information global to a tree of styled objects,

diff --git a/src/st/st-theme-node.c b/src/st/st-theme-node.c
index 1c2856b8fe4667732c140da97edafc04d4cbb015..79ec931338b1859ba054dca7a1ab09dc850e7200 100644 (file)
--- a/src/st/st-theme-node.c
+++ b/src/st/st-theme-node.c
@@ -1476,7 +1476,7 @@ st_theme_node_get_outline_width (StThemeNode  *node)
  * @node: a #StThemeNode
  * @color: (out caller-allocates): location to store the color
  *
- * Returns the color of @node's outline.
+ * Gets the color of @node's outline.
  */
 void
 st_theme_node_get_outline_color (StThemeNode  *node,
@@ -1745,7 +1745,7 @@ _st_theme_node_ensure_background (StThemeNode *node)
  * @node: a #StThemeNode
  * @color: (out caller-allocates): location to store the color
  *
- * Returns @node's background color.
+ * Gets @node's background color.
  */
 void
 st_theme_node_get_background_color (StThemeNode  *node,
@@ -1773,7 +1773,7 @@ st_theme_node_get_background_image (StThemeNode *node)
  * @node: a #StThemeNode
  * @color: (out caller-allocates): location to store the color
  *
- * Returns @node's foreground color.
+ * Gets @node's foreground color.
  */
 void
 st_theme_node_get_foreground_color (StThemeNode  *node,
@@ -1847,7 +1847,7 @@ st_theme_node_get_background_gradient (StThemeNode    *node,
  * @side: a #StSide
  * @color: (out caller-allocates): location to store the color
  *
- * Returns the color of @node's border on @side
+ * Gets the color of @node's border on @side
  */
 void
 st_theme_node_get_border_color (StThemeNode  *node,

diff --git a/src/st/st-theme-node.h b/src/st/st-theme-node.h
index 46d38b6aa8b8c5c86c7efede15ec25f02a289641..795f875c1824e726388627bb1e79f60666eb437f 100644 (file)
--- a/src/st/st-theme-node.h
+++ b/src/st/st-theme-node.h
@@ -31,7 +31,7 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:StThemeNode
+ * SECTION:st-theme-node
  * @short_description: style information for one node in a tree of themed objects
  *
  * A #StThemeNode represents the CSS style information (the set of CSS properties) for one

diff --git a/src/st/st-theme.c b/src/st/st-theme.c
index 2058e32f1a4f564b88ddcc2528c852555397f5c4..551fb2c1fed3b790d309a2d20c9feaf4b416ef00 100644 (file)
--- a/src/st/st-theme.c
+++ b/src/st/st-theme.c
@@ -491,10 +491,12 @@ pseudo_class_add_sel_matches_style (StTheme         *a_this,
 }
 
 /**
- *@param a_add_sel the class additional selector to consider.
- *@param a_node the style node to consider.
- *@return TRUE if the class additional selector matches
- *the style node given in argument, FALSE otherwise.
+ * class_add_sel_matches_style:
+ * @a_add_sel: The class additional selector to consider.
+ * @a_node: The style node to consider.
+ *
+ * Returns: %TRUE if the class additional selector matches
+ * the style node given in argument, %FALSE otherwise.
  */
 static gboolean
 class_add_sel_matches_style (CRAdditionalSel *a_add_sel,

diff --git a/src/st/st-theme.h b/src/st/st-theme.h
index 0a044bf3e62303ff599fadb4ff3b375ca1ead4ad..eb0103f9262261418547f523a2e6d295dc7abfe4 100644 (file)
--- a/src/st/st-theme.h
+++ b/src/st/st-theme.h
@@ -27,7 +27,7 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:StTheme
+ * SECTION:st-theme
  * @short_description: a set of stylesheets
  *
  * #StTheme holds a set of stylesheets. (The "cascade" of the name